QuickTime Music Architecture

| Previous | Chapter Contents | Chapter Top | Next |

MIDI Component Functions

This section describes the functions that are implemented by MIDI components.

These functions implemented by MIDI components are MIDI device drivers, and are called by the note allocator MIDI routines.

NAGetMIDIPorts is the correct call for you to make. You should not call QTMIDI .

QTMIDIGetMIDIPorts

You use the QTMIDIGetMIDIPorts function to get two lists of MIDI ports supported by the specified MIDI component: a list of ports that can receive MIDI input and a list of ports that can send MIDI output.

pascal ComponentResult QTMIDIGetMIDIPorts (
                     QTMIDIComponent ci,
                     QTMIDIPortListHandle *inputPorts,
                     QTMIDIPortListHandle *outputPorts);
ci
Specifies the instance of a MIDI component. Your software obtains this reference when calling the Component Manager's OpenComponent or OpenDefaultComponent function. See the "Component Manager" chapter in QuickTime 3 Reference.

inputPorts
A list of the MIDI ports supported by the component that can receive MIDI input.

outputPorts
A list of the MIDI ports supported by the component that can send MIDI output.

DISCUSSION

The caller of this function must dispose of the inputPorts and outputPorts handles.

QTMIDISendMIDI

You use the QTMIDISendMIDI function to send MIDI data to a MIDI port.

pascal ComponentResult QTMIDISendMIDI (
                     QTMIDIComponent ci,
                     long portIndex,
                     MusicMIDIPacket *mp);
ci
Specifies the instance of a MIDI component. Your software obtains this reference when calling the Component Manager's OpenComponent or OpenDefaultComponent function. See the "Component Manager" chapter in QuickTime 3 Reference.

portIndex
The index of the MIDI port to use for this operation.

mp
A pointer to the MIDI data packet to send.

DISCUSSION

The QTMIDISendMIDI function can be called at interrupt time. However, the same interrupt level is used whenever MIDI data is sent by the specified MIDI component.

QTMIDIUseReceivePort

You use the QTMIDIUseReceivePort function to allocate a MIDI port for input or to release the port.

pascal ComponentResult QTMIDIUseReceivePort (
                     QTMIDIComponent ci,
                     long portIndex,
                     MusicMIDIReadHookUPP readHook,
                     long refCon);
ci
Specifies the instance of a MIDI component. Your software obtains this reference when calling the Component Manager's OpenComponent or OpenDefaultComponent function. See the "Component Manager" chapter in QuickTime 3 Reference.

portIndex
The index of the MIDI port to use for this operation.

readHook
A pointer to a function in your software that receives incoming MIDI data packets, or nil to release the port.

refCon
A reference constant passed to the function specified by the readHook parameter.

DISCUSSION

The MIDI component delivers only MIDI data packets that contain only a single status byte.

QTMIDIUseSendPort

You use the QTMIDIUseSendPort function to allocate a MIDI port for output or to release the port.

pascal ComponentResult QTMIDIUseSendPort (
                     QTMIDIComponent ci,
                     long portIndex,
                     long inUse);
ci
Specifies the instance of a MIDI component. Your software obtains this reference when calling the Component Manager's OpenComponent or OpenDefaultComponent function. See the "Component Manager" chapter in QuickTime 3 Reference.

portIndex
The index of the MIDI port for this operation.

inUse
Specifies whether to allocate the MIDI port for output (if the value is 1 ) or to release the port (if the value is 0 ).

Functions for Importing MIDI Files

This section describes functions you use to control the importation of MIDI files.

MIDIImportGetSettings

You use the MIDIImportGetSettings function to get settings that control the importation of MIDI files.

pascal ComponentResult MIDIImportGetSettings (
                     TextExportComponent ci,
                     long *setting);
ci
Specifies the instance of the text export component used to import a MIDI file. Your software obtains this reference when calling the Component Manager's OpenComponent or OpenDefaultComponent function. See the "Component Manager" chapter in QuickTime 3 Reference.

setting
Flags that control the importation of MIDI files. These flags are described in "MIDI File Import Flags" .

DISCUSSION

The flags correspond to the checkboxes in the MIDI Import Options dialog box.

MIDIImportSetSettings

You use the MIDIImportSetSettings function to set settings that control the importation of MIDI files.

pascal ComponentResult MIDIImportSetSettings (
                     TextExportComponent ci,
                     long setting);
ci
Specifies the instance of the text export component used to import a MIDI file. Your software obtains this reference when calling the Component Manager's OpenComponent or OpenDefaultComponent function. See the "Component Manager" chapter in QuickTime 3 Reference.

setting
Flags that control the importation of MIDI files. These flags are described in "MIDI File Import Flags" .

DISCUSSION

The flags correspond to the checkboxes in the MIDI Import Options dialog box.

Function Provided by the Generic Music Component

The generic music component implements the following function that a client music component can call.

MusicGenericConfigure

You use the MusicGenericConfigure function to tell the generic music component what services your music component requires and to point to any resources that are necessary.

pascal ComponentResult MusicGenericConfigure (
                     MusicComponent mc,
                     long mode,
                     long flags,
                     long baseResID);
mc
Specifies the instance of the generic music component. Your software obtains this reference when calling the Component Manager's OpenComponent or OpenDefaultComponent function. See the "Component Manager" chapter in QuickTime 3 Reference.

mode
Must be 0 .

flags
Flags that control the importation of MIDI files.

baseResID
The resource ID of the lowest-numbered resource used by your music component.

These are the possible flags for the flags parameter:

kGenericMusicDoMIDI
Implement normal MIDI messages for note, controllers, and program changes 0-127.

kGenericMusicBank0...kGenericMusicBank32
If kGenericMusicBank0 is set, then bank changes for instruments numbered above 127 will be sent on controller zero; if kGenericMusicBank32 , then on controller 32. If both flags are set, then the bank is sent on controller zero, and then a zero value is sent to controller 32

kGenericMusicErsatzMIDI
Some musical devices, such as NuBus cards, may internally be driven by a MIDI stream but should not appear to the user to be an external MIDI device. The kGenericMusicErsatzMIDI flag instructs the generic music component to allocate channels appropriately and construct MIDI packets. The MIDI packets are always sent to the routine MusicDerivedMIDISend , and never to an external MIDI port.

kGenericMusicCallKnobs
Specifies that your music component should receive calls to its routine MusicDerivedSetKnob for changes to global or part knobs. This flag should be set if your component implements any knobs.

kGenericMusicCallParts
Specifies that your music component should receive calls to its routine MusicDerivedSetPart , in order to alter a specific part's polyphony or, in the case of a MIDI device, MIDI channel number.

kGenericMusicCallInstrument
Specifies that your music component should receive calls to its routine MusicDerivedSetInstrument , in order to set a part to a new instrument. This is for devices that support complete user-instruments with knob lists. If this flag is not set, then the generic music component calls your music component many times to set the value of each knob in the instrument.

kGenericMusicCallNumber
Directs the generic music component to call your music component's MusicDerivedSetInstrumentNumber function, rather than sending standard MIDI program-change and bank-change messages.

kGenericMusicCallROMInstrument
Allows instruments that appear to the user as instruments built into the synthesizer to be stored in the derived component's resource file, as 'ROMi' resources. The derived component gets a call to MusicDerivedSetInstrument when one of these instruments is requested.

DISCUSSION

The baseResID parameter is the lowest resource ID used by your component for the standard resources described above. Since the resource numbers are relative to this, you can include several music components in a single system extension.

Functions Implemented by e Generic Music Component Clients

The following functions are implemented by client music components of the generic music component. They are called by the generic music component, which make calls that are necessary for responding to function calls made directly by applications.

MusicDerivedSetKnob

The generic music component calls your music component's MusicDerivedSetKnob function when any of the synthesizer's knobs are altered.

pascal ComponentResult MusicDerivedSetKnob(
                     MusicComponent mc,
                     long knobType,
                     long knobNumber,
                     long knobValue,
                     long partNumber,
                     GCPart *p,
                     GenericKnobDescription *gkd);
 ComponentCallNow (kMusicDerivedSetKnobSelect,24);
mc
Specifies the instance of the generic music component. Your software obtains this reference when calling the Component Manager's OpenComponent or OpenDefaultComponent function. See the "Component Manager" chapter in QuickTime 3 Reference.

knobType
Specifies the type of knob that has been altered.

knobNumber
Specifies the number of the knob that has been altered.

knobValue
Specifies the new value of the altered knob.

partNumber
Specifies the number of the part whose knob has been altered.

p
A pointer to the part whose knob has been altered.

gkd
A generic knob description structure for the knob.

DISCUSSION

This function is called when any knob on the synthesizer is altered. It should look at the Part structure and the GenericKnobDescription structure and address the synthesizer hardware appropriately to set the new knob value. For a MIDI device, this means to construct a system-exclusive MIDI packet and send it to the MIDI routine received by the MusicDerivedSetMIDI call.

These are the possible values for the knobType parameter:

#define kGenericMusicKnob 1
#define kGenericMusicInstrumentKnob 2
#define kGenericMusicDrumKnob 3

MusicDerivedSetPart

The generic music component calls your music component's MusicDerivedSetPart function to use the polyphony for the part specified in the Part structure.

pascal ComponentResult MusicDerivedSetPart (
                     MusicComponent mc,
                     long partNumber,
                     GCPart *p);
 ComponentCallNow (kMusicDerivedSetPartSelect, 8);
mc
Specifies the instance of the generic music component. Your software obtains this reference when calling the Component Manager's OpenComponent or OpenDefaultComponent function.

partNumber
Specifies the number of the part for this operation.

p
A pointer to the part for this operation.

MusicDerivedSetInstrument

The generic music component calls your music component's MusicDerivedSetInstrument function to get the complete instrument defined by the Part structure to the synthesizer. This is either by hardware addressing in the case of a NuBus card, or by constructing a MIDI packet for an external synthesizer.

pascal ComponentResult MusicDerivedSetInstrument (
                     MusicComponent mc,
                     long partNumber,
                     GCPart *p);
 ComponentCallNow (kMusicDerivedSetInstrumentSelect,8);
mc
Specifies the instance of the generic music component. Your software obtains this reference when calling the Component Manager's OpenComponent or OpenDefaultComponent function. See the "Component Manager" chapter in QuickTime 3 Reference.

partNumber
Specifies the number of the part for this operation.

p
A pointer to the part for this operation.

MusicDerivedSetInstrumentNumber

The generic music component calls your music component's MusicDerivedSetInstrumentNumber function to set the specified part to the instrument number in the Part structure.

pascal ComponentResult MusicDerivedSetInstrumentNumber (
                     MusicComponent mc,
                     long partNumber,
                     GCPart *p);
 ComponentCallNow (kMusicDerivedSetInstrumentNumberSelect,8);
mc
Specifies the instance of the generic music component. Your software obtains this reference when calling the Component Manager's OpenComponent or OpenDefaultComponent function. See the "Component Manager" chapter in QuickTime 3 Reference.

partNumber
Specifies the number of the part for this operation.

p
A pointer to the part for this operation.

DISCUSSION

For a MIDI device that either only supports instruments from 0 to 127 or that supports one of the standard bank-switching controller messages, this call should not be needed. You would set the kGenericMusicBank0 or kGenericMusicBank32 (or both) flags, instead.

MusicDerivedSetMIDI

The generic music component calls your music component's MusicDerivedSetMIDI function to set the MIDI channel and other MIDI settings for MIDI output only. It sends MIDI out to the synthesizer.

pascal ComponentResult MusicDerivedSetMIDI(
                     MusicComponent mc,
                     MusicMIDISendUPP midiProc,
                     long refcon,
                     long midiChannel);
 ComponentCallNow (kMusicDerivedSetMIDISelect,12);
mc
Specifies the instance of the generic music component. Your software obtains this reference when calling the Component Manager's OpenComponent or OpenDefaultComponent function. See the "Component Manager" chapter in QuickTime 3 Reference.

midiProc
A pointer to the function in your music component for performing MIDI output.

refcon
A reference constant sent to the function specified by the midiProc parameter.

midiChannel
Specifies the MIDI channel to use for the operation.

DISCUSSION

A derived component for a MIDI synthesizer receives this call soon after it is opened. It should store the midiProc , refCon , and midiChannel in its global variables. When the derived component needs to communicate with the synthesizer, it calls the midiProc with this reference constant. The midiChannel variable specifies the "system channel" of the device.

MusicDerivedStoreInstrument

The generic music component calls your music component's MusicDerivedStoreInstrument function to store the specified instrument in a user instrument location.

pascal ComponentResult MusicDerivedStoreInstrument (
                     MusicComponent mc,
                     long partNumber,
                     GCPart *p,
                     long instrumentNumber )
 ComponentCallNow (kMusicDerivedStoreInstrumentSelect,8);
mc
Specifies the instance of the generic music component. Your software obtains this reference when calling the Component Manager's OpenComponent or OpenDefaultComponent function. See the "Component Manager" chapter in QuickTime 3 Reference.

partNumber
Specifies the number of the part for this operation.

p
A pointer to the part for this operation.

instrumentNumber
Specifies the number of the instrument to store.

© 1998 Apple Computer, Inc.

| Previous | Chapter Contents | Chapter Top | Next |